From c627d7299bcaf9c9b25292c4ad9e48b399772503 Mon Sep 17 00:00:00 2001 From: Havoc Pennington Date: Sat, 12 Jan 2002 04:39:07 +0000 Subject: [PATCH] sgml fixes 2002-01-11 Havoc Pennington * gtk/running.sgml: sgml fixes * gtk/tmpl/gtksignal.sgml: sgml fixes * gtk/tmpl/gtklabel.sgml: do the intro section 2002-01-11 Havoc Pennington * gtk/gtklabel.c: put in more links to Pango markup format docs (gtk_label_set_justify): mention gtk_misc_set_alignment --- ChangeLog | 5 + ChangeLog.pre-2-0 | 5 + ChangeLog.pre-2-10 | 5 + ChangeLog.pre-2-2 | 5 + ChangeLog.pre-2-4 | 5 + ChangeLog.pre-2-6 | 5 + ChangeLog.pre-2-8 | 5 + docs/reference/ChangeLog | 8 ++ docs/reference/gtk/running.sgml | 23 ++-- docs/reference/gtk/tmpl/gtk-unused.sgml | 6 - docs/reference/gtk/tmpl/gtkaccellabel.sgml | 2 +- docs/reference/gtk/tmpl/gtklabel.sgml | 129 ++++++++++++++++++++- docs/reference/gtk/tmpl/gtkpaned.sgml | 7 ++ docs/reference/gtk/tmpl/gtksignal.sgml | 2 +- docs/reference/gtk/tmpl/gtkwidget.sgml | 4 +- gtk/gtklabel.c | 19 +-- 16 files changed, 205 insertions(+), 30 deletions(-) diff --git a/ChangeLog b/ChangeLog index 9d472601d5..a85eccb125 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2002-01-11 Havoc Pennington + + * gtk/gtklabel.c: put in more links to Pango markup format docs + (gtk_label_set_justify): mention gtk_misc_set_alignment + 2002-01-12 Tor Lillqvist Fixes contributed by Archaeopteryx Software: This is a first small diff --git a/ChangeLog.pre-2-0 b/ChangeLog.pre-2-0 index 9d472601d5..a85eccb125 100644 --- a/ChangeLog.pre-2-0 +++ b/ChangeLog.pre-2-0 @@ -1,3 +1,8 @@ +2002-01-11 Havoc Pennington + + * gtk/gtklabel.c: put in more links to Pango markup format docs + (gtk_label_set_justify): mention gtk_misc_set_alignment + 2002-01-12 Tor Lillqvist Fixes contributed by Archaeopteryx Software: This is a first small diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10 index 9d472601d5..a85eccb125 100644 --- a/ChangeLog.pre-2-10 +++ b/ChangeLog.pre-2-10 @@ -1,3 +1,8 @@ +2002-01-11 Havoc Pennington + + * gtk/gtklabel.c: put in more links to Pango markup format docs + (gtk_label_set_justify): mention gtk_misc_set_alignment + 2002-01-12 Tor Lillqvist Fixes contributed by Archaeopteryx Software: This is a first small diff --git a/ChangeLog.pre-2-2 b/ChangeLog.pre-2-2 index 9d472601d5..a85eccb125 100644 --- a/ChangeLog.pre-2-2 +++ b/ChangeLog.pre-2-2 @@ -1,3 +1,8 @@ +2002-01-11 Havoc Pennington + + * gtk/gtklabel.c: put in more links to Pango markup format docs + (gtk_label_set_justify): mention gtk_misc_set_alignment + 2002-01-12 Tor Lillqvist Fixes contributed by Archaeopteryx Software: This is a first small diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4 index 9d472601d5..a85eccb125 100644 --- a/ChangeLog.pre-2-4 +++ b/ChangeLog.pre-2-4 @@ -1,3 +1,8 @@ +2002-01-11 Havoc Pennington + + * gtk/gtklabel.c: put in more links to Pango markup format docs + (gtk_label_set_justify): mention gtk_misc_set_alignment + 2002-01-12 Tor Lillqvist Fixes contributed by Archaeopteryx Software: This is a first small diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6 index 9d472601d5..a85eccb125 100644 --- a/ChangeLog.pre-2-6 +++ b/ChangeLog.pre-2-6 @@ -1,3 +1,8 @@ +2002-01-11 Havoc Pennington + + * gtk/gtklabel.c: put in more links to Pango markup format docs + (gtk_label_set_justify): mention gtk_misc_set_alignment + 2002-01-12 Tor Lillqvist Fixes contributed by Archaeopteryx Software: This is a first small diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8 index 9d472601d5..a85eccb125 100644 --- a/ChangeLog.pre-2-8 +++ b/ChangeLog.pre-2-8 @@ -1,3 +1,8 @@ +2002-01-11 Havoc Pennington + + * gtk/gtklabel.c: put in more links to Pango markup format docs + (gtk_label_set_justify): mention gtk_misc_set_alignment + 2002-01-12 Tor Lillqvist Fixes contributed by Archaeopteryx Software: This is a first small diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 838711553d..7210bd3087 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,11 @@ +2002-01-11 Havoc Pennington + + * gtk/running.sgml: sgml fixes + + * gtk/tmpl/gtksignal.sgml: sgml fixes + + * gtk/tmpl/gtklabel.sgml: do the intro section + 2002-01-09 Matthias Clasen * gtk/tmpl/gtkaccellabel.sgml: Remove duplicate docs. diff --git a/docs/reference/gtk/running.sgml b/docs/reference/gtk/running.sgml index 5cdf669b59..a73f775430 100644 --- a/docs/reference/gtk/running.sgml +++ b/docs/reference/gtk/running.sgml @@ -20,8 +20,9 @@ How to run and debug your GTK+ application All GTK+ applications support a number of standard commandline -options. These are removed from argv by -gtk_init(). Modules may parse and remove further options. +options. These are removed from argv by gtk_init(). Modules may parse and remove +further options. @@ -37,7 +38,10 @@ A list of modules to load in addition to those specified in the <systemitem>--g-fatal-warnings</systemitem> -Make GTK+ abort on all warnings. +Make GTK+ abort on all warnings. This is useful to stop on the first +warning in a debugger, if your application is printing multiple +warnings. It's almost always best to start debugging with the first +warning that occurs. @@ -188,7 +192,7 @@ or DISPLAY; mostly to determine paths to look for certain files. Visual feedback about window updates - The special value all can be used to turn on all debug options. + The special value all can be used to turn on all debug options. @@ -209,7 +213,7 @@ or DISPLAY; mostly to determine paths to look for certain files. (If GTK_EXE_PREFIX is defined, <libdir> is $GTK_EXE_PREFIX/lib. Otherwise it is the libdir specified when GTK+ was configured, usually - /usr/local/lib.) + /usr/local/lib.) For each directory in the list, GTK+ actually looks first in a subdirectory named after the version number of GTK+, then in the directory itself and finally in the system-specific library path. @@ -247,9 +251,9 @@ or DISPLAY; mostly to determine paths to look for certain files. the RC files, which in turn overwrites the default value <sysconfdir>/gtk-2.0/gtk.immodules (<sysconfdir> is the sysconfdir specified when GTK+ was configured, - usually /usr/local/etc.) + usually /usr/local/etc.) - + <envar>GTK_RC_FILES</envar> @@ -257,6 +261,7 @@ or DISPLAY; mostly to determine paths to look for certain files. Specifies a list of RC files to parse instead of the default ones; see Resource Files. + @@ -272,7 +277,7 @@ or DISPLAY; mostly to determine paths to look for certain files. <envar>GTK_DATA_PREFIX</envar> - If set, makes GTK+ use $GTK_DATA_PREFIX + If set, makes GTK+ use $GTK_DATA_PREFIX instead of the prefix configured when GTK+ was compiled. @@ -318,7 +323,7 @@ nevertheless. Information about XIM support - The special value all can be used to turn on all debug options. + The special value all can be used to turn on all debug options. diff --git a/docs/reference/gtk/tmpl/gtk-unused.sgml b/docs/reference/gtk/tmpl/gtk-unused.sgml index 456bfeb3dd..a3bb8b493e 100644 --- a/docs/reference/gtk/tmpl/gtk-unused.sgml +++ b/docs/reference/gtk/tmpl/gtk-unused.sgml @@ -2550,12 +2550,6 @@ Internal function used by #GtkHPaned and #GtkVPaned @child1_req: @child2_req: - - -Old name for gtk_paned_set_handle_size(). - - - Set the the handle size to @size x @size pixels. diff --git a/docs/reference/gtk/tmpl/gtkaccellabel.sgml b/docs/reference/gtk/tmpl/gtkaccellabel.sgml index 27460fd6e3..a781002931 100644 --- a/docs/reference/gtk/tmpl/gtkaccellabel.sgml +++ b/docs/reference/gtk/tmpl/gtkaccellabel.sgml @@ -118,7 +118,7 @@ Creates a new #GtkAccelLabel. @accel_label: -@accel_widget: +@accel_widget: diff --git a/docs/reference/gtk/tmpl/gtklabel.sgml b/docs/reference/gtk/tmpl/gtklabel.sgml index b3e18791f6..707e7d4fc2 100644 --- a/docs/reference/gtk/tmpl/gtklabel.sgml +++ b/docs/reference/gtk/tmpl/gtklabel.sgml @@ -6,11 +6,132 @@ A widget that displays a small to medium amount of text. -The #GtkLabel widget is usually used directly by the programmer to display -word(s) describing an adjacent widget or its use. It is also used internally -by Gtk+ as #GtkButton labels, #GtkMenu items, and many other widgets which -use text. +The #GtkLabel widget displays a small amount of text. As the name +implies, most labels are used to label another widget such as a +#GtkButton, a #GtkMenuItem, or a #GtkOptionMenu. + + + +Mnemonics + + +Labels may contain mnemonics. Mnemonics are +underlined characters in the label, used for keyboard navigation. +Mnemonics are created by providing a string with an underscore before +the mnemonic character, such as "_File", to the +functions gtk_label_new_with_mnemonic() or +gtk_label_set_text_with_mnemonic(). + + + +Mnemonics automatically activate any activatable widget the label is +inside, such as a #GtkButton; if the label is not inside the +mnemonic's target widget, you have to tell the label about the target +using gtk_label_set_mnemonic_widget(). Here's a simple example where +the label is inside a button: + + + + /* Pressing Alt+H will activate this button */ + button = gtk_button_new (); + label = gtk_label_new_with_mnemonic ("_Hello"); + gtk_container_add (GTK_CONTAINER (button), label); + + +There's a convenience function to create buttons with a mnemonic label +already inside: + + + + /* Pressing Alt+H will activate this button */ + button = gtk_button_new_with_mnemonic ("_Hello"); + + + +To create a mnemonic for a widget alongside the label, such as a +#GtkEntry, you have to point the label at the entry with +gtk_label_set_mnemonic_widget(): + + + /* Pressing Alt+H will focus the entry */ + entry = gtk_entry_new (); + label = gtk_label_new_with_mnemonic ("_Hello"); + gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry); + + + + + + + + +Markup (styled text) + + +To make it easy to format text in a label (changing colors, fonts, +etc.), label text can be provided in a simple markup format. +Here's how to create a label with a small font: + + + label = gtk_label_new (NULL); + gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>"); + + +(See complete documentation of available +tags in the Pango manual.) + + +The markup passed to gtk_label_set_markup() must be valid; for +example, literal </>/& characters must be escaped as +&lt;, &gt;, and &amp;. If you pass text obtained from +the user, file, or a network to gtk_label_set_markup(), +you'll want to escape it with g_markup_escape_text(). + +Markup strings are just a convenient way to set the #PangoAttrList on +a label; gtk_label_set_attributes() may be a simpler way to set +attributes in some cases. Be careful though; #PangoAttrList tends to +cause internationalization problems, unless you're applying attributes +to the entire string (i.e. unless you set the range of each attribute +to [0, G_MAXINT)). The reason is that specifying the start_index and +end_index for a #PangoAttribute requires knowledge of the exact string +being displayed, so translations will cause problems. + + + + +Selectable labels + + +Labels can be made selectable with gtk_label_set_selectable(). +Selectable labels allow the user to copy the label contents to +the clipboard. Only labels that contain useful-to-copy information +— such as error messages — should be made selectable. + + + + +Text layout + + +A label can contain any number of paragraphs, but will have +performance problems if it contains more than a small number. +Paragraphs are separated by newlines or other paragraph separators +understood by Pango. + + +Labels can automatically wrap text if you call +gtk_label_set_line_wrap(). + + +gtk_label_set_justify() sets how the lines in a label align +with one another. If you want to set how the label as a whole +aligns in its available space, see gtk_misc_set_alignment(). + + + diff --git a/docs/reference/gtk/tmpl/gtkpaned.sgml b/docs/reference/gtk/tmpl/gtkpaned.sgml index 1e3b1df6b8..33f24283a3 100644 --- a/docs/reference/gtk/tmpl/gtkpaned.sgml +++ b/docs/reference/gtk/tmpl/gtkpaned.sgml @@ -95,6 +95,13 @@ parameters. This is equivalent to @child: the child to add + + +Old name for gtk_paned_set_handle_size(). + + + + Old name for gtk_paned_set_gutter_size(). diff --git a/docs/reference/gtk/tmpl/gtksignal.sgml b/docs/reference/gtk/tmpl/gtksignal.sgml index 827568577f..ec510317dc 100644 --- a/docs/reference/gtk/tmpl/gtksignal.sgml +++ b/docs/reference/gtk/tmpl/gtksignal.sgml @@ -7,7 +7,7 @@ Object methods and callbacks. The GTK+ signal system merely proxies the GLib signal system now. For future -usage, direct use of the GSignal API is recommended, this avoids significant +usage, direct use of the GSignal API is recommended, this avoids significant performance hits where #GtkArg structures have to be converted into #GValues. diff --git a/docs/reference/gtk/tmpl/gtkwidget.sgml b/docs/reference/gtk/tmpl/gtkwidget.sgml index 736f571294..8b7e56523f 100644 --- a/docs/reference/gtk/tmpl/gtkwidget.sgml +++ b/docs/reference/gtk/tmpl/gtkwidget.sgml @@ -76,8 +76,8 @@ Tells about certain properties of the widget. @GTK_COMPOSITE_CHILD: Indicates that the widget is a composite child of its parent; see gtk_widget_push_composite_child(), gtk_widget_pop_composite_child(). -@GTK_NO_REPARENT: - Unused since before GTK+ 1.2, will be removed in a future version. +@GTK_NO_REPARENT: + Unused since before GTK+ 1.2, will be removed in a future version. @GTK_APP_PAINTABLE: Set and unset by gtk_widget_set_app_paintable(). Must be set on widgets whose window the application directly draws on, diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c index 96f0899a87..9940f0d8fd 100644 --- a/gtk/gtklabel.c +++ b/gtk/gtklabel.c @@ -1054,7 +1054,7 @@ set_markup (GtkLabel *label, * @label: a #GtkLabel * @str: a markup string (see Pango markup format) * - * Parses @str which is marked up with the Pango text markup language, + * Parses @str which is marked up with the Pango text markup language, * setting the label's text and attribute list based on the parse results. **/ void @@ -1075,7 +1075,7 @@ gtk_label_set_markup (GtkLabel *label, * @label: a #GtkLabel * @str: a markup string (see Pango markup format) * - * Parses @str which is marked up with the Pango text markup language, + * Parses @str which is marked up with the Pango text markup language, * setting the label's text and attribute list based on the parse results. * If characters in @str are preceded by an underscore, they are underlined * indicating that they represent a keyboard accelerator called a mnemonic. @@ -1192,7 +1192,10 @@ gtk_label_set_pattern (GtkLabel *label, * * Sets the alignment of the lines in the text of the label relative to * each other. %GTK_JUSTIFY_LEFT is the default value when the - * widget is first created with gtk_label_new(). + * widget is first created with gtk_label_new(). If you instead want + * to set the alignment of the label as a whole, use + * gtk_misc_set_alignment() instead. gtk_label_set_justify() has no + * effect on labels containing only a single line. **/ void gtk_label_set_justify (GtkLabel *label, @@ -2640,8 +2643,9 @@ gtk_label_get_layout_offsets (GtkLabel *label, * @label: a #GtkLabel * @setting: %TRUE if the label's text should be parsed for markup. * - * Sets whether the text of the label contains markup in Pango's - * text markup lango. See gtk_label_set_markup(). + * Sets whether the text of the label contains markup in Pango's text markup + * language. See gtk_label_set_markup(). **/ void gtk_label_set_use_markup (GtkLabel *label, @@ -2657,8 +2661,9 @@ gtk_label_set_use_markup (GtkLabel *label, * gtk_label_get_use_markup: * @label: a #GtkLabel * - * Returns whether the label's text is interpreted as marked up with the - * Pango text markup language. See gtk_label_set_use_markup (). + * Returns whether the label's text is interpreted as marked up with + * the Pango text markup + * language. See gtk_label_set_use_markup (). * * Return value: %TRUE if the label's text will be parsed for markup. **/ -- 2.30.2